API request examples

View and modify tenant settings (PowerShell)

The IPS Manager API typically handles the different categories of server settings by responding to a GET request with a complete collection of settings in a (large) JSON object. And to modify one or more of those settings, you must send a POST request that contains the entire JSON object.

To illustrate this process, the following PowerShell commands show how to retrieve and view the tenant settings, and then performing an enable/disable of a tenant by modifying the settings JSON object.

First the tenant settings are retrieved:

PS> $serverUrl = 'https://ipsserver.mycompany.com'

PS> $response = Invoke-RestMethod -Uri "$serverUrl/admin/api/TenantSettings/GetTenantSettings" -UseDefaultCredentials

From the contents of '$response' we want to view the settings for the client availability of each tenant, and the availability of the Planning Space and cx SUITE applications:

PS> $response.tenants | Select-Object -Property tenantName, isEnabled, tenantApplicationsGroup

tenantName   isEnabled tenantApplicationsGroup                                                         
----------   --------- -----------------------                                                         
AtlantisGold      True {@{groupName=PlanningSpace; enabled=True}, @{groupName=cx SUITE; enabled=True}}
UAT-testing       True {@{groupName=PlanningSpace; enabled=True}, @{groupName=cx SUITE; enabled=True}} 

Currently everything is available (enabled is True).

Make a copy of '$response' which is going to be the object to be sent in the POST request:

PS> $requestObject = $response.PSObject.Copy()

Modify $requestObject so that the first tenant will be disabled:

PS> $requestObject.tenants[0].isEnabled = $false

Also, disable client access to cx SUITE applications for the second tenant:

PS> $requestObject.tenants[0].tenantApplicationsGroup[1].enabled = $false

Now POST these changes to the API server:

PS> Invoke-RestMethod -Method Post -Uri "$serverUrl/admin/api/TenantSettings/UpdateSettings" -UseDefaultCredentials `
   -headers @{'Content-Type'= 'application/json'}  -body ($requestObject | ConvertTo-Json -Depth 10)

Here, the $requestObject is converted to JSON for inclusion in the API request body: note the use of the Depth option for 'ConvertTo-JSON' because the default value for Depth (which is 2) leads to an incorrect JSON object.

If the API request is successful, you will see this response:

warnings errors serverSpecificResponses
-------- ------ -----------------------
{}       {}     {} 

Note: there are alternative, direct API methods to enable or disable a tenant, see 'POST /admin/api/TenantSettingsCommands/DisableTenant' and 'POST /admin/api/TenantSettingsCommands/EnableTenant'.

Note also: many configuration functions provided by the IPS Manager API can be run directly as PowerShell cmdlets. This requires installation of the IPS PowerShell module. For information see the Planning Space Deployment Guide.

Request and view historical server monitor data (PowerShell)

This example shows a script which retrieves data about IPS Server usage using the Server Monitor API and generates a chart using the .NET DataVisualization.Charting library.

First, load the .NET code assembly into your PowerShell with the command:

PS> Add-Type -AssemblyName "System.Windows.Forms.DataVisualization"

Download this script: PS-DataVizChart.ps1.txt. Use mouse-right-click and 'Save link as...' to save it as a file; remove the '.txt' from the filename (this is included because your browser may be configured not to accept 'ps1' script files). The script contains several functions needed to create a chart. Run the script like this:

PS> . .\PS-DataVizChart.ps1

Note the first '.' (dot-source operator) is crucial because the functions need to be defined in the local scope, not the script scope.

Now for the main script. You can also download a copy of it here: Admin-API-Chart-Example.ps1.txt.

# Get data from the IPS Admin API
$serverUrl = 'https://ipsserver.mycompany.com'

# API request must use dates expressed in Epoch Time (i.e. the number of seconds since 01/01/1970)
$dateMinus1day =[math]::Round((Get-Date -Date ((Get-Date).ToUniversalTime()) -UFormat %s)) - (3600*24)
$dat = Invoke-RestMethod -Uri "$serverUrl/monitor/api/metricgroups/1/servers/1/historicaldata?startDate=$dateMinus1day" -UseDefaultCredentials

<# DATA TO BE PLOTTED
N = $dat.timeline.count
X points = $dat.timeline
Y points = $dat.metricData[0].data
Y axis title = $dat.metricData[0].metricItemName
#>

# Create a chart object
$Chart1 = New-Chart -width 1024 -height 800 -ChartTitle $ChartTitle -WithChartArea $true -WithChartLegend $false
$ChartTitle      = ("IPS Server Monitor - Server 1 - last 24 hours - {0}" -f $dat.metricData[0].metricItemName)
$ChartSeriesType = [System.Windows.Forms.DataVisualization.Charting.SeriesChartType]::Line
$ChartSeriesHTMLColor = $null

# Chart area settings
$Chart1.ChartAreas[0].Name              = "DefaultArea"
$Chart1.ChartAreas[0].AxisY.Title       = $dat.metricData[0].metricItemName
$Chart1.ChartAreas[0].AxisX.Title       = "Time"
$Chart1.ChartAreas[0].AxisX.LabelStyle.Format = "yyyy-MM-dd HH:mm"
  
# Chart Series creation
$ChartSeries = New-ChartSeries -SeriesName "Series" -LegendName "Chart Legend" –ChartAreaName "DefaultArea" -ChartType $ChartSeriesType -HTMLColor $ChartSeriesHTMLColor
$Chart1.Series.Add($ChartSeries)
 
Foreach ($i in 1..$dat.timeline.count) {
    [void]$Chart1.Series["Series"].Points.AddXY(
        (Get-Date -Date "01/01/1970").AddSeconds($dat.timeline[$i-1]), $dat.metricData[0].data[$i-1] 
        # converting Epoch Time values in $dat to date-time objects
    )
}

# Display the chart object
Display-Chart -Chart2Display $Chart1 -Title "IPS Server monitor: $serverUrl"

To run the script, again the dot-source operator will be required to run in the local scope:

PS> . .\Admin-API-Chart-Example.ps1

You can see that '$dat' will contain historical data from 'metric group 1' which is CPU usage, measured for server 1. Data points are extracted from $dat and (in the 'foreach' loop) set up as (X,Y) pairs for the chart functions to process.

The API method expects datetimes in API requests to be expressed as Epoch times, and the returned data (in the 'timeline' array) is likewise expressed using Epoch times. Epoch time (also known as 'Unix time') is the number of seconds elapsed since the start of 01/01/1970. Notice how 'Get-Date' is used to set up '$dateMinus1day' in Epoch time. Then later the operation (Get-Date -Date "01/01/1970").AddSeconds($dat.timeline[$i-1]) is used to convert back from Epoch time to a standard datetime object in PowerShell.

The screenshot below shows a sample output from the script.